// =====================================================================================
// 
//       Filename:  protocol.h
// 
//    Description:  Definition of functions used to communicate with the remote web
//    				service
// 
//        Version:  1.0
//        Created:  22/09/2010 23:23:35
//       Revision:  none
//       Compiler:  gcc
// 
//         Author:  François Hissel (fh), francois.hissel@m4x.org
//        Company:  
// 
// =====================================================================================


#ifndef  PROTOCOL_INC
#define  PROTOCOL_INC

#include	"webrequest.h"
#include	"pathutils.h"

/**
 * \brief Persistent data of the connection
 *
 * This structure holds the persistent data needed for the application to stay connected to the remote host.
 */
struct Persistent {
	Cookies *cookies;	//!< List of cookies sent by the application
	char *host;	//!< Host name
	Folder *tree;	//!< Local copy of the distant folders tree, used for caching purposes
	struct addrinfo *hostinfo;	//!< IP address of the host
	char *username;	//!< User identifier
	char *password;	//!< Password of the user
	pthread_mutex_t lock;	//!< Mutex to guarantee that only one thread can read/write the structure at the same time
} persistent;


/**
 * \brief Initialize resources used to communicate with the remote website
 *
 * This function initializes some resources. It should be called at the start of the program, before any try to connect to the remote website.
 */
void init_resources();

/**
 * \brief Free all resources used by the program
 *
 * This function releases all the resources allocated by the program, to allow for a normal and clean exit. It frees the memory, closes the files and sockets.
 */
void free_resources();

/**
 * \brief Connect to the web service with the given username and password
 *
 * This function connects to the file storing web service with the username and password given as parameters. It returns 0 for a successful connection and a different value if an error occurred.
 * \param host Name of the web service
 * \param port Port of the web service
 * \param user User name
 * \param password Password of the user
 * \return 0 if everything went fine, another value if an error occurred
 */
int connect_service(char *host,char *port,char *user,char *password);

/**
 * \brief Get a pointer to a folder structure
 *
 * This function makes sure the information of a folder or a file have been loaded from the remote web site, and returns a pointer on the corresponding Folder structure
 * \param path Virtual path of the file
 * \param folder Pointer to the folder structure in memory
 * \return 0 if everything went fine, 1 if the file could not be found, -1 if an error occurred
 */
int get_node(const char *path,Folder **folder);

/**
 * \brief List the contents of a folder
 *
 * This function lists all the contents of a folder. It automatically goes through all the web pages describing this folder if more than one page are used to display all the contents.
 * \param folder Name of the folder
 * \return 0 if everything went fine, 1 if the folder does not exist, -1 if an error occurred
 */
int list_folder(const char *folder);

/**
 * \brief Download a file
 *
 * This function downloads the file at the given location.
 * \param path Path and name of the file
 * \param localpath Local path of the file on which the remote one should be copied
 * \return 0 if everything went fine, 1 if the file does not exist, -1 if an error occurred
 */
int download_file(const char *path,const char *localpath);

/**
 * \brief Upload a file
 *
 * This function uploads a file to the chosen folder. It uses two POST requests, one to set AJAX parameters (xajax, xajaxr and xajaxargs) and it actually finds the address where it should post the new file. This latter is then sent with another POST request.
 * \param pathname Virtual path on the new file on the remote server, this is not the actual path on the website, but the path to the file in the folder tree
 * \param filename Future name of the file on the web server
 * \param file Path of the local file to upload on the web server
 * \return 0 if everything went fine, 1 if the remote path does not exist, -1 if an error occurred
 */
int upload_file(const char *pathname,const char *filename,const char *file);

/**
 * \brief Move a file
 *
 * This function moves a file on the web server from one path to another.
 * \param source Virtual path of the file on the remote server. This is not the actual path on the website, but the path to the file in the folder tree
 * \param dest Virtual path of the file after the move operation. The same remark as above applies
 * \return 0 if everything went fine, 1 if the source file could not be found, 2 if the destination path does not exist, -1 if an error occurred
 */
int move_file(const char *source,const char *dest);

/**
 * \brief Delete a file
 *
 * This function deletes a file on the web server.
 * \param path Virtual path of the file on the remote server. This is not the actual path on the website, but the path to the file in the folder tree
 * \return 0 if everything went fine, 1 if the source file could not be found, -1 if an error occurred
 */
int delete_file(const char *path);

/**
 * \brief Make a new folder
 *
 * This function creates a new folder at the given path.
 * \param path Virtual path of the new folder on the remote server. The parent folder should already exist.
 * \return 0 if everything went fine, 1 if the parent folder could not be found, -1 if an error occurred
 */
int make_dir(const char *path);

#endif   // ----- #ifndef PROTOCOL_INC  -----
